home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / utils / xad / developer / include / autodocs / xadmaster.doc next >
Text File  |  1999-01-01  |  31KB  |  856 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadmaster.library/--general--
  4. xadmaster.library/xadAllocObject
  5. xadmaster.library/xadCalcCRC16
  6. xadmaster.library/xadCalcCRC32
  7. xadmaster.library/xadConvertDates
  8. xadmaster.library/xadDiskUnArc
  9. xadmaster.library/xadFileUnArc
  10. xadmaster.library/xadFreeInfo
  11. xadmaster.library/xadFreeObject
  12. xadmaster.library/xadGetClientInfo
  13. xadmaster.library/xadGetErrorText
  14. xadmaster.library/xadGetInfo
  15. xadmaster.library/xadHookAccess
  16. xadmaster.library/xadRecogFile
  17. xadmaster.library/--tags--
  18. xadmaster.library/--data hooks--
  19.  
  20. VERSION
  21.     $VER: xadmaster.doc 1.5 (14.03.1999) by SDI
  22.  
  23. xadmaster.library/--general--                   xadmaster.library/--general--
  24.  
  25.     This library gives you an interface to extract data from file or disk
  26.     archives.
  27.  
  28.     When unachiving a archive you need to do following steps always
  29.     1) Allocate a "struct xadArchiveInfo" with a call to
  30.        xadAllocObjectA(XADOBJ_ARCHIVEINFO, 0). This structure is the master
  31.        interface and must not by modified in any way. Nearly all other
  32.        functions you may use need to get the pointer this this structure.
  33.        All data is passed with tags!
  34.     1) Call xadGetInfo() to find out if the input data is archived. If it
  35.        is, the xadArchiveInfo structure is filled with lots of information
  36.        (but the structure may contain empty lists!).
  37.        See xadGetInfo() description to see what you may read and what stuff
  38.        not. One of the input tags must be specified here to specify one 
  39.        of the allowed 4 input stream methods.
  40.     2) For every file in a file archive or every disk call xadFileUnArc() or
  41.        xadDiskUnArc() with one tag XAD_ENTRYNUMBER set to wanted entry. One
  42.        of the output tags must be specified here. For xadFileUnArc() there are
  43.        4 streams methods like for input. The xadDiskUnArc() function allows a
  44.        fifth method called XAD_OUTDEVICE. This one writes directly to disks
  45.        like all the disk archivers do. It allows 2 ways to specify the
  46.        destination device.
  47.        Passwords and other stuff is additionally allowed and sometimes
  48.        required.
  49.     3) Call xadFreeInfo() to free the stuff allocated with xadGetInfo.
  50.     4) Use xadFreeObjectA() to free the xadArchiveInfo structure.
  51.     Do not use one xadArchiveInfo file structure for multiple input files!
  52.     
  53.     ANY needed structure must be allocated with xadAllocObject! None of
  54.     the xadmaster structures can be allocated any other way!
  55.  
  56.     There exist lots of tags, which can be passed to the functions of this
  57.     library. Some of these are repeated in the xadArchiveInfo communication
  58.     structure. Do NEVER set this flags or values directly, but always use
  59.     the corresponding tags. The handling of these elements possibly will
  60.     change, but the tags will stay valid always!
  61.  
  62.     I know there are lots of flags which have long and strange names. The
  63.     method is not so complicated as you may think. The always follow following
  64.     guideline: XADxxY_zzzzz
  65.     xx - short name of their structure (AI - xadArchiveInfo, DI - xadDiskInfo,
  66.          C - xadClient, ...)
  67.     Y  - F for flag or B for bit value
  68.     zz - The flag name itself
  69.     So XADPIF_OVERWRITE is a flag for xadProgressInfo, which is called
  70.     OVERWRITE and XADAIB_OVERWRITE is a bit value for xadArchiveInfo structure.
  71.     
  72.     Also all the structure elements cover a short prefix indicating the name
  73.     of the master structure (xfi for xadFileInfo, xc for xadClient, ...). So
  74.     you can always check if your code is valid by comparing the prefixes.
  75.  
  76. xadmaster.library/xadAllocObject             xadmaster.library/xadAllocObject
  77.  
  78.     NAME
  79.         xadAllocObject - Allocate memory for all xad related structures
  80.  
  81.     SYNOPSIS
  82.         ptr = xadAllocObjectA(type, tags)
  83.         D0                    D0    A0
  84.  
  85.         APTR xadAllocObjectA(ULONG, struct TagItem *)
  86.  
  87.         ptr = xadAllocObject(type, tag1, ...)
  88.  
  89.         APTR xadAllocObject(ULONG, Tag, ...)
  90.  
  91.     FUNCTION
  92.         This function allocates the memory of a needed xad related
  93.         structure and initializes it. You need to use this function to
  94.         allocate the structures. Any other way of allocating is not
  95.         allowed.
  96.  
  97.     INPUT
  98.         type    - in libraries/xadmaster.h defined XADOBJ_... types.
  99.                   For example XADOBJ_FILEINFO allocates xadFileInfo
  100.                   structure.
  101.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  102.           XAD_OBJNAMESIZE, XAD_OBJCOMMENTSIZE, XAD_OBJBLOCKENTRIES,
  103.           XAD_OBJPRIVINFOSIZE
  104.  
  105.     RESULT
  106.         ptr     - Pointer to required structure or 0 when an error occured.
  107.  
  108.     SEE ALSO
  109.         libraries/xadmaster.h, xadFreeObject(), tags section
  110.  
  111. xadmaster.library/xadCalcCRC16                 xadmaster.library/xadCalcCRC16
  112.  
  113.     NAME
  114.         xadCalcCRC16 - calculate a 16 bit CRC
  115.  
  116.     SYNOPSIS
  117.         crc16 = xadCalcCRC16(id, init, size, buffer)
  118.         D0                   D0   D1    D2     A0
  119.  
  120.     UWORD xadCalcCRC16(UWORD, UWORD, ULONG, STRPTR)
  121.  
  122.     FUNCTION
  123.     This function calculates a 16 bit CRC. It is possibly to choose the
  124.     calculation method by parameter mode.
  125.  
  126.     The CRC calculation uses a table built with following function:
  127.     void MakeCRC16(UWORD *buf, ULONG ID)
  128.     {
  129.         UWORD i, j, k;
  130.  
  131.       for(i = 0; i < 256; ++i)
  132.       {
  133.         k = i;
  134.  
  135.         for(j = 0; j < 8; ++j)
  136.         {
  137.           if(k & 1)
  138.             k = (k >> 1) ^ ID;
  139.           else
  140.             k >>= 1;
  141.         }
  142.         buf[i] = k;
  143.       }
  144.     }
  145.  
  146.     The used calculation routine is like that:
  147.         crc = init;
  148.         while(size--)
  149.           crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8);
  150.  
  151.     ID's defined in xadmaster.h use a default table. All others build the
  152.     table on the fly.
  153.     XADCRC16_ID1: (0xA001) - Used by DMS, Arc, ...
  154.  
  155.     INPUT
  156.     id    - The table creation ID (maybe XADCR16_ID value)
  157.     init    - The initial value for CRC calculation.
  158.         size    - The input buffer size.
  159.         buffer  - A pointer to the input buffer.
  160.  
  161.     RESULT
  162.         crc16    - The calculated CRC value.
  163.  
  164.     SEE ALSO
  165.         libraries/xadmaster.h, xadCalcCRC32
  166.  
  167. xadmaster.library/xadCalcCRC32                 xadmaster.library/xadCalcCRC32
  168.  
  169.     NAME
  170.         xadCalcCRC32 - calculate a 32 bit CRC
  171.  
  172.     SYNOPSIS
  173.         crc32 = xadCalcCRC32(id, init, size, buffer)
  174.         D0                   D0   D1    D2     A0
  175.  
  176.     ULONG xadCalcCRC32(ULONG, ULONG, ULONG, STRPTR)
  177.  
  178.     FUNCTION
  179.     This function calculates a 32 bit CRC. It is possibly to choose the
  180.     calculation method by parameter mode.
  181.  
  182.     The CRC calculation uses a table built with following function:
  183.     void MakeCRC32(ULONG *buf, ULONG ID)
  184.     {
  185.         ULONG i, j, k;
  186.  
  187.       for(i = 0; i < 256; ++i)
  188.       {
  189.         k = i;
  190.  
  191.         for(j = 0; j < 8; ++j)
  192.         {
  193.           if(k & 1)
  194.             k = (k >> 1) ^ ID;
  195.           else
  196.             k >>= 1;
  197.         }
  198.         buf[i] = k;
  199.       }
  200.     }
  201.  
  202.     The used calculation routine is like that:
  203.         crc = init;
  204.         while(size--)
  205.           crc = tab[(crc ^ *buffer++) & 0xFF] ^ (crc >> 8);
  206.  
  207.     ID's defined in xadmaster.h use a default table. All others build the
  208.     table on the fly.
  209.     XADCRC32_ID2: (0xEDB88320) - Used by Zoom, Zip, LZX, ...
  210.  
  211.     INPUT
  212.     id    - The table creation ID (maybe XADCR32_ID value)
  213.     init    - The initial value for CRC calculation.
  214.         size    - The input buffer size.
  215.         buffer  - A pointer to the input buffer.
  216.  
  217.     RESULT
  218.         crc32    - The calculated CRC value.
  219.  
  220.     SEE ALSO
  221.         libraries/xadmaster.h, xadCalcCRC16
  222.  
  223. xadmaster.library/xadConvertDates           xadmaster.library/xadConvertDates
  224.  
  225.     NAME
  226.         xadConvertDates - convert between date storage methods
  227.  
  228.     SYNOPSIS
  229.         result = xadConvertDatesA(tags)
  230.         D0                         A0
  231.  
  232.     LONG xadConvertDates(struct TagItem *)
  233.  
  234.         result = xadConvertDates(tag1, ...)
  235.  
  236.     LONG xadConvertDates(Tag, ...)
  237.  
  238.     FUNCTION
  239.     This function can be used to transfrom date and time between
  240.     different storage systems. One of the input tags must be specified.
  241.     Output tags may be specified multiple. The date information is
  242.     based on Gregorian calendar. Some systems can store a wider range
  243.     of dates than others. If a date produces an overflow or an
  244.     underflow for a special date, the highest/lowest valid date is used
  245.     (e.g. for timevalues 0x00000000 or 0xFFFFFFFF).
  246.  
  247.     The XAD_MAKEGMTDATE and XAD_MAKELOCALDATE tags need locale.library
  248.     to get the offset to local time. If locale.library cannot be opened
  249.     the offset is set to 0.
  250.  
  251.     XAD_DATECURRENTTIME can be used to get the current system date and
  252.     time.
  253.  
  254.     WeekDay information is ignored for input and always recalculated.
  255.     The calculation routines use full range of available variable space,
  256.     so f.e. a Unix date 1.1.1970 00:00:00 (value 0x00000000) with a
  257.     UTC offset of -30 min produces 31.12.1968 23:30:00 (which cannot be
  258.     stored as UNIX time value, but only as xadDate structure)!.
  259.  
  260.     INPUT
  261.     ai    - the master communication structure
  262.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  263.           XAD_DATEUNIX, XAD_DATEAMIGA, XAD_DATEDATESTAMP,
  264.               XAD_DATEXADDATE, XAD_DATECLOCKDATA, XAD_DATECURRENTTIME,
  265.               XAD_GETDATEUNIX, XAD_GETDATEAMIGA,
  266.               XAD_GETDATEDATESTAMP, XAD_GETDATEXADDATE,
  267.               XAD_GETDATECLOCKDATA, XAD_MAKEGMTDATA, XAD_MAKELOCALDATE
  268.  
  269.     RESULT
  270.         result    - any of the XADERR codes or zero when all is ok.
  271.  
  272.     SEE ALSO
  273.         libraries/xadmaster.h, tags section
  274.  
  275. xadmaster.library/xadDiskUnArc                 xadmaster.library/xadDiskUnArc
  276.  
  277.     NAME
  278.         xadDiskUnArc - the master function for unarchiving disks
  279.  
  280.     SYNOPSIS
  281.         result = xadDiskUnArcA(ai, tags)
  282.         D0                    A0   A1
  283.  
  284.     LONG xadDiskUnArc(struct xadArchiveInfo *, struct TagItem *)
  285.  
  286.         result = xadDiskUnArc(ai, tag1, ...)
  287.  
  288.     LONG xadDiskUnArc(struct xadArchiveInfo *, Tag, ...)
  289.  
  290.     FUNCTION
  291.     This function dearchives a disk archive. It can be called after
  292.     a succesful call to xadGetInfo. At least the tag XAD_ENTRYNUMBER
  293.     and one of the output tags needs to be supplied. When a progress
  294.     hook is supplied, this can be used for questioning for overwriting
  295.     and ignoring of drive geometry and for status displays.
  296.     Normally disk archivers will have only one entry, but there may
  297.     be multiple disk archives.
  298.  
  299.     When this function returns, the supplied output data streams may
  300.     be used in any way (files, memory). The library does not even know
  301.     that they exist! The xadmaster.library cannot be used to rename,
  302.     protect, comment or delete that stuff!
  303.  
  304.     INPUT
  305.     ai    - the master communication structure
  306.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  307.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  308.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  309.           XAD_PROGRESSHOOK, XAD_IGNOREGEOMETRY, XAD_HIGHCYLINDER,
  310.           XAD_LOWCYLINDER, XAD_OUTDEVICE, XAD_VERIFY, XAD_PASSWORD
  311.  
  312.     RESULT
  313.         result    - any of the XADERR codes or zero when all is ok.
  314.  
  315.     SEE ALSO
  316.         libraries/xadmaster.h, xadFileUnArc(), xadGetInfo(), tags section
  317.  
  318. xadmaster.library/xadFileUnArc                 xadmaster.library/xadFileUnArc
  319.  
  320.     NAME
  321.         xadFileUnArc - the master function for unarchiving disks
  322.  
  323.     SYNOPSIS
  324.         result = xadFileUnArcA(ai, tags)
  325.         D0                    A0   A1
  326.  
  327.     LONG xadFileUnArc(struct xadArchiveInfo *, struct TagItem *)
  328.  
  329.         result = xadFileUnArc(ai, tag1, ...)
  330.  
  331.     LONG xadFileUnArc(struct xadArchiveInfo *, Tag, ...)
  332.  
  333.     FUNCTION
  334.     This function dearchives a file archive entry. It can be called
  335.     after a succesful call to xadGetInfo. At least the tag
  336.     XAD_ENTRYNUMBER and one of the output tags needs to be supplied.
  337.     When a progress hook is supplied, this can be used for questioning
  338.     for overwriting and for status displays.
  339.     This function needs to be called for every file, which should be
  340.     unarchived. Best is to do unarchiving in direction giving by
  341.     info structure, because some archivers crunch multiple files in one
  342.     pass and the unarchiver needs to compress and buffer the whole
  343.     pass to get one file.
  344.  
  345.     When this function returns, the supplied output data streams may
  346.     be used in any way (files, memory). The library does not even know
  347.     that they exist! The xadmaster.library cannot be used to rename,
  348.     protect, comment or delete that stuff!
  349.  
  350.     INPUT
  351.     ai    - the master communication structure
  352.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  353.                 XAD_ENTRYNUMBER, XAD_OUTFILEHANDLE, XAD_OUTFILENAME,
  354.           XAD_OUTHOOK, XAD_OUTMEMORY, XAD_OUTSIZE, XAD_OVERWRITE,
  355.           XAD_PROGRESSHOOK, XAD_PASSWORD
  356.  
  357.     RESULT
  358.         result    - any of the XADERR codes or zero when all is ok.
  359.  
  360.     SEE ALSO
  361.         libraries/xadmaster.h, xadDiskUnArc(), xadGetInfo(), tags section
  362.  
  363. xadmaster.library/xadFreeInfo                   xadmaster.library/xadFreeInfo
  364.  
  365.     NAME
  366.         xadFreeInfo - free stuff built and allocated with xadGetInfo()
  367.  
  368.     SYNOPSIS
  369.         xadFreeInfo(ai)
  370.                     A0
  371.  
  372.         void xadFreeInfo(struct xadArchiveInfo *)
  373.  
  374.     FUNCTION
  375.         Frees all the stuff built and allocated by a call to xadGetInfo().
  376.     You always need to call this after your work with a certain input
  377.     file is finished.
  378.  
  379.     INPUTS
  380.         ai    - the master communication structure
  381.  
  382.     SEE ALSO
  383.         libraries/xadmaster.h, xadGetInfo(), tags section
  384.  
  385. xadmaster.library/xadFreeObject               xadmaster.library/xadFreeObject
  386.  
  387.     NAME
  388.         xadFreeObject - Frees structures allocated with xadAllocObject()
  389.  
  390.     SYNOPSIS
  391.         xadFreeObjectA(object, tags)
  392.                          A0      A1
  393.  
  394.         void xadFreeObjectA(APTR, struct TagItem *)
  395.  
  396.         xadFreeObject(object, tag1, ...)
  397.  
  398.         void xadFreeObject(APTR, Tag, ...)
  399.  
  400.     FUNCTION
  401.         Frees object allocated by xadAllocObject(). Do not call for objects
  402.         allocated in any other way.
  403.         This function frees ALL memory which was allocated by xadAllocObject(),
  404.         but only this memory. This means all name buffers and other related
  405.         structures are freed, but if you replace pointers, your replacements
  406.         get not freed. This function does not need the original pointers to be
  407.         in the related positions, as the buffer size is stored elsewhere.
  408.  
  409.     INPUTS
  410.         object    - object allocated with xadAllocObject()
  411.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  412.           currently none
  413.  
  414.     SEE ALSO
  415.         libraries/xadmaster.h, xadAllocObject(), tags section
  416.  
  417. xadmaster.library/xadGetClientInfo         xadmaster.library/xadGetClientInfo
  418.  
  419.     NAME
  420.         xadGetClientInfo - Get list of active clients
  421.  
  422.     SYNOPSIS
  423.         ptr = xadGetClientInfo()
  424.         D0
  425.  
  426.         struct xadClient *xadGetClientInfo(void)
  427.  
  428.     FUNCTION
  429.     This function returns a list of all active clients. It can be used
  430.     to show information about the library. The list is read only and
  431.     cannot be modified!
  432.  
  433.     RESULT
  434.         ptr    - Pointer to first client in the list.
  435.  
  436.     SEE ALSO
  437.         libraries/xadmaster.h
  438.  
  439. xadmaster.library/xadGetErrorText           xadmaster.library/xadGetErrorText
  440.  
  441.     NAME
  442.         xadGetErrorText - Get error string from an error number
  443.  
  444.     SYNOPSIS
  445.         ptr = xadGetErrorText(errnum)
  446.         D0                    D0
  447.  
  448.         STRPTR xadGetErrorText(ULONG)
  449.  
  450.     FUNCTION
  451.     This function returns the error string related to the supplied
  452.     error number. This string is valid as long as xadmaster.library
  453.     is opened, so when needed any longer time it must be copied.
  454.  
  455.     INPUT
  456.         errnum    - in libraries/xadmaster.h defined XADERR_... numbers.
  457.  
  458.     RESULT
  459.         ptr    - Pointer to required string.
  460.  
  461.     SEE ALSO
  462.         libraries/xadmaster.h
  463.  
  464. xadmaster.library/xadGetInfo                     xadmaster.library/xadGetInfo
  465.  
  466.     NAME
  467.         xadGetInfo - get information about an archive
  468.  
  469.     SYNOPSIS
  470.         result = xadGetInfoA(ai, tags)
  471.         D0                    A0   A1
  472.  
  473.     LONG xadGetInfo(struct xadArchiveInfo *, struct TagItem *)
  474.  
  475.         result = xadGetInfo(ai, tag1, ...)
  476.  
  477.     LONG xadGetInfo(struct xadArchiveInfo *, Tag, ...)
  478.  
  479.     FUNCTION
  480.     This function returns all useful information about a specified
  481.     archive. It opens the archive for working. You may call
  482.     xadFileUnArc() or xadDiskUnArc() for the included entries
  483.     after a successful call to xadGetInfo. The data must be freed
  484.     by a call to xadFreeInfo(). After that the xadArchiveInfo structure
  485.     must be freed and NEVER be used again! For archives encrypting
  486.     the information parts as well, you need to specify XAD_PASSWORD.
  487.     This password can be used for all calls to a unarchiving function,
  488.     but is overwritten by XAD_PASSWORD tag argument (only for the
  489.     entry XAD_PASSWORD is specified). Check and parse the elements
  490.     xai_FileInfo and xai_DiskInfo. You may expect both lists to have
  491.     valid entries or also both to be empty. Parsing the lists is the
  492.     normal way to do anything.
  493.  
  494.     The supplied input stream is used and must be valid and unmodified
  495.     until xadFreeInfo() is called. Only the current client is allowed to
  496.     access the stream, but it is guaranteed to be unmodified!
  497.  
  498.     INPUT
  499.     ai    - the master communication structure
  500.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  501.           XAD_INSIZE, XAD_INFILENAME, XAD_INFILEHANDLE,
  502.           XAD_INMEMORY, XAD_INHOOK, XAD_PASSWORD
  503.  
  504.     RESULT
  505.         result    - any of the XADERR codes or zero when all is ok.
  506.  
  507.     SEE ALSO
  508.         libraries/xadmaster.h, xadFreeInfo(), xadDiskUnArc(),
  509.         xadFileUnArc(), tags section
  510.  
  511. xadmaster.library/xadHookAccess               xadmaster.library/xadHookAccess
  512.  
  513.     NAME
  514.         xadHookAccess - a client only function to get/store data
  515.  
  516.     SYNOPSIS
  517.         result = xadHookAccess(command, data, buffer, ai)
  518.         D0                       D0      D1     A0    A1
  519.  
  520.     LONG xadHookAccess(ULONG, LONG, APTR, struct xadArchiveInfo *)
  521.  
  522.     FUNCTION
  523.     This function is for external clients only. It is needed to get
  524.     data, store results and seek in input or output. There are 5
  525.     commands XADAC_READ, XADAC_WRITE, XADAC_COPY, XADAC_INPUTSEEK,
  526.     XADAC_OUTPUTSEEK to do that. This function updates the xai_InPos,
  527.     xai_OutPos and xai_OutSize fields in xadArchiveInfo structure. The
  528.     seek commands and the copy command should set buffer parameter to
  529.     zero. Seek's and reads should not exceed the file borders! The
  530.     client knows position and size, so checks are possible before doing
  531.     wrong commands.
  532.  
  533.     INPUT
  534.         command - one of the XADAC command to control hook
  535.         data    - the required data, mostly a size value
  536.         buffer    - the input/output buffer for read and write
  537.     ai    - the master communication structure
  538.  
  539.     RESULT
  540.         result    - any of the XADERR codes or zero when all is ok.
  541.  
  542.     SEE ALSO
  543.         libraries/xadmaster.h
  544.  
  545. xadmaster.library/xadRecogFile                 xadmaster.library/xadRecogFile
  546.  
  547.     NAME
  548.         xadRecogFile - check if a file is an archive file or not
  549.  
  550.     SYNOPSIS
  551.         client = xadRecogFileA(size, memory, tags)
  552.         D0                     D0     A0     A1
  553.  
  554.         struct xadClient *xadRecogFileA(ULONG, APTR, struct TagItem *)
  555.  
  556.         client = xadRecogFileA(size, memory, tag1, ...)
  557.  
  558.         struct xadClient *xadRecogFileA(ULONG, APTR, Tag, ...)
  559.  
  560.     FUNCTION
  561.     This function can be used to check if a file is a archive or not.
  562.     It has only limited abilities! You need to pass a pointer to
  563.     memory of recogsize. The recogsize value can be found in
  564.     xadMasterBase. If the file is shorter, use the complete file as
  565.     buffer. Longer buffers are allowed as well. When the file is
  566.     archived, you get back a pointer to the client which detected the
  567.     file. If not, the return is zero. The only usable information
  568.     should be the name of the client. To get more information and all
  569.     archive related data you have to use xadGetInfo, which calls
  570.     xadRecogFile internal itself.
  571.  
  572.     Normally this function is not needed by application programs. It
  573.     is used in xadList utility. This function is useful for tools
  574.     only detecting and displaying the archiver type.
  575.  
  576.     INPUT
  577.         size    - size of the memory region
  578.     memory    - pointer to the memory holding the file
  579.         tags    - Pointer to an array of struct TagItem. Recognized tags: 
  580.           XAD_NOEXTERN
  581.  
  582.     RESULT
  583.         client    - pointer to client structure or zero when no archive
  584.  
  585.     SEE ALSO
  586.         libraries/xadmaster.h, xadGetInfo(), tags section
  587.  
  588. xadmaster.library/--tags--                         xadmaster.library/--tags--
  589.  
  590.     TAGS FOR xadAllocObject
  591.  
  592.       XAD_OBJBLOCKENTRIES    (ULONG)
  593.     Can be specified together with XADOBJ_DISKINFO. This allocates
  594.     memory for xdi_BlockInfo. Data field of tag item contains number
  595.     of required blocks. Memory gets freed automatically, when object
  596.     is freed.
  597.  
  598.       XAD_OBJCOMMENTSIZE    (ULONG)
  599.     Like XAD_OBJNAMESIZE, but allocates memory for xfi_Comment entry.
  600.  
  601.       XAD_OBJNAMESIZE        (ULONG)
  602.     Can be specified together with XADOBJ_FILEINFO. This allocates
  603.     memory for storing file name. The required size has to be stored
  604.     in data field of tag item. The allocated memory pointer is stored
  605.     in xfi_FileName field of returned structure. Memory gets freed
  606.     automatically, when object is freed.
  607.  
  608.       XAD_OBJPRIVINFOSIZE    (ULONG)
  609.     Can be specified together with XADOBJ_FILEINFO and XADOBJ_DISKINFO.
  610.     This allocates longword aligned client private buffer, which is
  611.     stored in xfi_PrivateInfo or xdi_PrivateInfo field. The required
  612.     size has to be stored in data field of tag item. Memory gets freed
  613.     automatically, when object is freed.
  614.  
  615.     TAGS FOR xadGetInfo
  616.  
  617.       XAD_INFILEHANDLE        (BPTR)
  618.     FileHandle to get data from. It is not necessary that the handle
  619.     is at the beginning of the file.
  620.  
  621.       XAD_INFILENAME        (STRPTR)
  622.     Name of the input file.
  623.  
  624.       XAD_INHOOK        (struct Hook *)
  625.     This enables any other way of data delivering. See special
  626.     chapter on I/O hook functions.
  627.  
  628.       XAD_INMEMORY        (STRPTR)
  629.         Pointer to a memory buffer holding the input data. You need to
  630.         specify XAD_INSIZE when using this.
  631.  
  632.       XAD_INSIZE        (ULONG)
  633.     Specify the size of input data. Must be used together with
  634.     XAD_INMEMORY. Can be used together with other hooks.
  635.  
  636.     TAGS FOR xadFileUnArc and xadDiskUnArc
  637.  
  638.       XAD_ENTRYNUMBER        (ULONG)
  639.     This flag specifies the wanted entry. You must not specify more
  640.     or less than one of that flag every call. Normally this flag equals
  641.     the element xdi_EntryNumber for currently parsed xadDiskInfo
  642.     structure and xfi_EntryNumber for currently parsed xadFileInfo
  643.     structure.
  644.  
  645.       XAD_MAKEDIRECTORY        (BOOL)
  646.     Create missing directory tree when necessary. If not set the
  647.     progress hook may get asked if directory should be created or
  648.     not (if there is one).
  649.  
  650.       XAD_OUTFILEHANDLE        (BPTR)
  651.     FileHandle to send data to. It is not necessary that the handle
  652.     is at the beginning of the file.
  653.  
  654.       XAD_OUTFILENAME        (STRPTR)
  655.     Name of the output file.
  656.  
  657.       XAD_OUTHOOK        (struct Hook *)
  658.     This enables any other way of data storing. See special chapter
  659.     on I/O hook functions.
  660.  
  661.       XAD_OUTMEMORY        (STRPTR)
  662.         Pointer to a memory buffer to store data in. You need to specify
  663.         XAD_OUTSIZE when using this.
  664.  
  665.       XAD_OUTSIZE        (ULONG)
  666.     Specify the maximum size of output data. Must be used together with
  667.     XAD_OUTMEMORY.
  668.  
  669.       XAD_OVERWRITE        (BOOL)
  670.     This forces the file hook to overwrite existing destination files.
  671.     If not set the progress hook may get asked if files should be
  672.     overwritten or not (if there is one).
  673.  
  674.       XAD_PROGRESSHOOK        (struct Hook *)
  675.     The progress hook for status displays. This hook can be used to
  676.     do display completion reports or ask the user. It gets a pointer
  677.     to a xadProgressInfo structure. The hook returns a combination
  678.     of XADPIF flags. A value of zero means a break command.
  679.     The xpi_Status field must be checked and handled when XADPMODE_ASK
  680.     is used. When XADPIF_OVERWRITE is set, the hook must determine if
  681.     the file should be overwritten or not. The return flag
  682.     XADPIF_OVERWRITE must be set corresponding to this decision. Same
  683.     is for XADPIF_IGNORGEGEOMETRY and XADPIF_MAKEDIRECTORY flag.
  684.  
  685.     TAGS FOR xadDiskUnArc
  686.  
  687.       XAD_IGNOREGEOMETRY    (BOOL)
  688.     This forces the device hook to use devices with different drive
  689.     geometry than the one on disk archive. Most time this will produce
  690.     useless disks. If not set the progress hook may get asked if
  691.     geometry should be ignored or not (if there is one).
  692.  
  693.       XAD_HIGHCYLINDER        (ULONG)
  694.     It specifies the highest cylinder which should be unarchived.
  695.  
  696.       XAD_LOWCYLINDER        (ULONG)
  697.     It specifies the lowest cylinder which should be unarchived.
  698.  
  699.       XAD_OUTDEVICE        (struct xadDeviceInfo *)
  700.     For disk archives it is useful to store data directly on a disk.
  701.     Use this tag to specify the device where data should be stored.
  702.         In xdi_DOSName the DOS device must be stored, which must not be
  703.         terminated with a ':' character.
  704.         Alternatively in fields xdi_DeviceName and xdi_Unit the wanted
  705.         device must be specified. The device must support TD_GETGEOMETRY
  706.         command, even if XAD_IGNOREGEOMETRY is turned on, as the hook
  707.         needs at least the blocksize for internal buffering.
  708.         NOTE: When xdi_DeviceName and xdi_Unit is used, the hook cannot
  709.         perform an Inhibit operation and thus it cannot prevent other
  710.         tasks from accessing the device. Also a DOS device is not updated,
  711.         so a DiskChange becomes necessary.
  712.         I suggest always using xdi_DOSName field!
  713.       
  714.       XAD_VERIFY        (BOOL)
  715.         Turns on verify for device output. This is turned off by default.
  716.  
  717.     TAGS FOR xadConvertDates
  718.  
  719.       XAD_DATEUNIX        (ULONG)
  720.     Input is an UNIX date value (seconds starting with 01.01.1970).
  721.  
  722.       XAD_DATEAMIGA        (ULONG)
  723.     Input as an Amiga date value (seconds starting with 01.01.1978).
  724.  
  725.       XAD_DATEDATESTAMP        (struct DateStamp *)
  726.     Input is a pointer to an Amiga DateStamp structure.
  727.  
  728.       XAD_DATEXADDATE        (struct xadDate *)
  729.     Input is a pointer to a xadmaster date structure.
  730.  
  731.       XAD_DATECLOCKDATA        (struct ClockData *)
  732.     Input is a pointer to a ClockData structure.
  733.  
  734.       XAD_DATECURRENTTIME    (void)
  735.     Current system time value should be used as input.
  736.  
  737.       XAD_GETDATEUNIX        (ULONG *)
  738.     An UNIX time value should be stored in the ULONG variable, the
  739.     supplied pointer points to.
  740.  
  741.       XAD_GETDATEAMIGA        (ULONG *)
  742.     An Amiga time value should be stored in the ULONG variable, the
  743.     supplied pointer points to.
  744.  
  745.       XAD_GETDATEDATESTAMP    (struct DateStamp *)
  746.     The date should be stored in DateStamp structure the supplied
  747.     pointer points to.
  748.  
  749.       XAD_GETDATEXADDATE    (struct xadDate *)
  750.     The date should be stored in xadmaster date structure the supplied
  751.     pointer points to.
  752.  
  753.       XAD_GETDATECLOCKDATA    (struct ClockData *)
  754.     The date should be stored in ClockData structure the supplied
  755.     pointer points to.
  756.  
  757.       XAD_MAKEGMTDATE        (BOOL)
  758.     This forces the function to subtract the GMT offset supplied by
  759.     locale.library to convert a local date to GMT date. Opening
  760.     locale.library is required for that. When it cannot be openend or
  761.     the offset would cause a overrun or underrun in the xd_Year field,
  762.     no offset will be used. 
  763.       
  764.       XAD_MAKELOCALDATE        (BOOL)
  765.     This forces the function to ad the GMT offset supplied by
  766.     locale.library to convert a GMT date to a local date. Opening
  767.     locale.library is required for that. When it cannot be openend or
  768.     the offset would cause a overrun or underrun in the xd_Year field,
  769.     no offset will be used.
  770.  
  771.     TAGS FOR different functions
  772.  
  773.       XAD_NOEXTERN        (BOOL)
  774.     When this is specified for xadGetInfo or xadRecogFile, the library
  775.     skips any external clients. Normally this should not be necessary.
  776.     Some of the main clients are external as well (for legal reasons).
  777.  
  778.       XAD_PASSWORD        (STRPTR)
  779.     You may supply a password for xadGetInfo, xadFileUnArc and
  780.     xadDiskUnArc functions.
  781.  
  782. xadmaster.library/-- data hooks--            xadmaster.library/--data hooks--
  783.  
  784.     GENERAL
  785.     You have four methods of passing data to xadmaster.library: file-
  786.     names, filehandles, memory areas and hooks. The hooks are described
  787.     here. The hook field h_Entry has to be standard hook functions and
  788.     gets called with the hook itself in A0 and a pointer to a
  789.     xadHookParam in A1. Commands are stored in xhp_Command field, data
  790.     in the other fields. Return values are 0 or any of the XADERR codes.
  791.     Unsupported commands are returned with XADERR_NOTSUPPORTED.
  792.  
  793.     You may store a pointer to private data in the field xhp_PrivatePtr.
  794.     You always get a XADHC_FREE after work to enable you freeing your
  795.     resources.
  796.  
  797.     Whenever an error occured, the hook gets called with XADHC_ABORT.
  798.     Use this to delete partial file, free useless memory or whatever
  799.     you used. You must not do cleanup stuff on XADHC_ABORT call, as 
  800.     XADHC_FREE call follows after it.
  801.     
  802.         NOTE: Because hooks are not called in program environment, they
  803.         cannot be used in small data model of some compilers, as register
  804.         A4 is not passed through. So the hook either has to be compiled in
  805.         large data model or should use __saveds keyword of some compilers.
  806.  
  807.     COMMANDS
  808.       XADHC_READ        (input hooks only)
  809.     This command is called all time xadmaster.library needs some data.
  810.     Fill the supplied memory area with input data of needed size.
  811.     Input:    xhp_BufferSize    size of required data
  812.         xhp_BufferPtr    buffer to fill
  813.     Output:    xhp_DataPos    buffer position after read
  814.  
  815.       XADHC_WRITE        (output hooks only)
  816.     This function is called, when some data should be stored. Copy
  817.     the contents of buffer to your data storing system.
  818.     Input:    xhp_BufferSize    size of data
  819.         xhp_BufferPtr    pointer to memory area
  820.     Output:    xhp_DataPos    buffer position after write
  821.  
  822.       XADHC_SEEK        (both)
  823.     Change the current position in your data (like dos.library Seek
  824.     command). The offset you have to seek is always relative to
  825.     current position. It can be negative too. Seek's with size 0 can
  826.     be used to get current file position.
  827.     Input:    xhp_CommandData    offset you have to seek
  828.     Output:    xhp_DataPos    buffer position after seek
  829.  
  830.       XADHC_INIT        (both)
  831.     The work starts. Allocate needed structures and initialize your
  832.     stuff. Clear xhp_BufferPos.
  833.     Input:    none
  834.     Output:    none
  835.  
  836.       XADHC_FREE        (both)
  837.     You get this when work is finished, free all your stuff now. You
  838.     need to clear all pointers you use for checking, as it may happen
  839.     that you get multiple XADHC_FREE commands.
  840.     Input:    none
  841.     Output:    none
  842.  
  843.       XADHC_ABORT        (output hooks only)
  844.     You get this when work was aborted, because an error occured.
  845.     Free all work stuff. Buffers must be freed by later XADHC_FREE call.
  846.     Be prepared to get multiple XADHC_ABORT commands.
  847.     Input:    none
  848.     Output:    none
  849.  
  850.       XADHC_FULLSIZE        (input hooks only)
  851.     The hook should return complete size of input data which should be
  852.     processed.
  853.     Input:    none
  854.     Output:    xhp_CommandData    size of input file
  855.  
  856.